6  Software Design Description

6.1 Overall Description

6.1.1 Assumptions

  • The target platform is a Docker-compatible operating system (Preferably Linux).
  • The target web browser is Google Chrome.
  • All products are run and operated in the same machine (Monolithic architecture).
  • Only administrators can access the running system. Other users can only access the system through the frontend server.
  • The blockchain is a private blockchain.
  • The blockchain is an optional feature that can be turned on or off.
  • The database is a H2 database.
  • The mode of the database can be in-memory (for testing), file or remote (for production).

6.1.2 Design Constraints

  • The backend system is a REST API server.
  • The backend system is a Java application.
  • The blockchain is a Hyperledger Fabric blockchain.
  • There should be an option to turn on or off the blockchain. If the blockchain is turned off, the backend system should still work as a normal REST API server with a local database.

6.1.3 Technology Suggestion

  • The endpoints of the backend system can be exposed so that a node browser can be developed to search & access the endpoints and get the necessary information.

6.2 System Architecture Design

6.2.1 Overall Architecture

Figure 6.1: Overall architecture

Component Description
Chain Node (CN) A node of the blockchain. This stores the records and handles the history and transaction requests from the Request Server (Change/View the score, information, etc.)
Request Server The off-chain backend of a CN. This stores the pending requests from the user and is the only way to call a request to the CN. Each Request Server may have a different way to handle user requests (Voting, Direct Request, etc.)
Frontend Server Provide the UX/UI for interacting with the Request Server

6.2.2 System Architecture

6.2.3 Package Diagram

Figure 6.2: Package Diagram of Request Server

Package Name Description
root Main classes
api The abstract classes & interfaces
entity The entities of the database
handler The handlers of the endpoints of the REST API server
internal Internal classes used by other packages
internal/student The instances of the Student Updater
model The input / output objects
model/input The input objects for the handlers
model/output The output objects returned from the handlers
model/fabric The models used internally by the student updater

6.3 System Detailed Design

6.3.1 Class Specification

Figure 6.3: Class Diagram of the Request Server

6.3.1.1 Account

Field Name Type Description
id long The account id
username String The username
hashedPassword String The hashed password
salt String The salt of the password
role String The role of the account
createdAt Date The date when the account was created
classrooms List ClassTeacher The list of references to the classrooms that the account participates if its role is Teacher
recordEntries List RecordEntry The list of record entries related to the subjects the the account is teaching if its role is Teacher
requestedRecordEntries List RecordEntry The list of verified record entries that the account requested to changes
approvedRecordEntries List RecordEntry The list of verified record entries that the account accepted
pendingRecordEntries List PendingRecordEntry The list of pending record entries related to the subjects the the account is teaching if its role is Teacher
requestedPendingRecordEntries List PendingRecordEntry The list of pending record entries that the account requested to changes
homeClassrooms List Classroom The list of classrooms the the account is a homeroom teacher at

6.3.1.2 Profile

Field Name Type Description
id long The account id
account Account The reference to the Account object
firstName String The first name
lastName String The last name
male boolean Is the person male? false if she is a female
avatar String The link to the avatar image
birthDate Date The date of the birthday
address String The address
phone String The phone number
email String The email
updated boolean The flag indicates that the profile requires sychronization with the Chain Node

6.3.1.3 Student

Field Name Type Description
id long The account id
account Account The reference to the Account object
ethnic String The ethnic of the student
fatherName String The name of the father of the student
fatherJob String The job of the father of the student
motherName String The name of the mother of the student
motherJob String The job of the mother of the student
guardianName String The name of the guardian of the student
guardianJob String The job of the guardian of the student
homeTown String The home town of the student
classrooms List ClassStudent The list of references to the classrooms that the student participates
records List Record The list of records related to the classrooms that the student participates
updaterKey List UpdaterKey The list of updater keys of the student. Used to allow outsiders to get infomation of the student.

6.3.1.4 Classroom

Field Name Type Description
id long The classroom id
name String The name of the classroom
grade int The grade of the classroom
year int The year of the classroom
homeroomTeacher Account The reference to the homeroom teacher of the classroom
students List ClassStudent The list of references to the students that participate in the classroom
teachers List ClassTeacher The list of references to the teachers that participate in the classroom
records List Record The list of records related to the classroom

6.3.1.5 ClassStudent

Field Name Type Description
id long The id of the reference
classroom Classroom The reference to the classroom
student Student The reference to the student

6.3.1.6 ClassTeacher

Field Name Type Description
id long The id of the reference
classroom Classroom The reference to the classroom
teacher Account The reference to the teacher
subjectId long The id of the subject that the teacher teaches

6.3.1.7 Record

Field Name Type Description
id long The record id
classroom Classroom The reference to the classroom
student Student The reference to the student
recordEntry List RecordEntry The list of verified record entries related to the record
pendingRecordEntry List PendingRecordEntry The list of pending record entries related to the record

6.3.1.8 RecordEntry

Field Name Type Description
id long The record entry id
subjectId long The id of the subject that the record entry is related to
firstHalfScore int The score of the first semester of the subject
secondHalfScore int The score of the second semester of the subject
finalScore int The final score of the subject
requestDate Date The date when the record entry was requested
approvalDate Date The date when the record entry was approved
updateComplete boolean The flag indicates that the record entry was updated to the Chain Node
teacher Account The reference to the teacher that teaches the subject
requester Account The reference to the account that requested the record entry
approver Account The reference to the account that approved the record entry
record Record The reference to the record that the record entry is related to

6.3.1.9 PendingRecordEntry

Field Name Type Description
id long The pending record entry id
subjectId long The id of the subject that the pending record entry is related to
firstHalfScore int The score of the first semester of the subject
secondHalfScore int The score of the second semester of the subject
finalScore int The final score of the subject
requestDate Date The date when the pending record entry was requested
teacher Account The reference to the teacher that teaches the subject
requester Account The reference to the account that requested the pending record entry
record Record The reference to the record that the pending record entry is related to

6.3.1.10 UpdaterKey

Field Name Type Description
id String The unique key
student Student The reference to the student that the key is related to

6.3.1.11 StatisticKey

Field Name Type Description
id String The unique key
year int The year that the key is referred to
grade int The grade that the key is referred to

6.3.2 Sequence Diagram

6.3.2.1 Create Account

6.3.2.2 Get Account

6.3.2.3 Get Account List

6.3.2.4 Login

6.3.2.5 Update Account Password

6.3.2.6 Update Account Profile

6.3.2.7 Create Classroom

6.3.2.8 Add Students To Classroom

6.3.2.9 Remove Students From Classroom

6.3.2.10 Add Teachers To Classroom

6.3.2.11 Remove Teachers From Classroom

6.3.2.12 Update Classroom

6.3.2.13 Get Classroom

6.3.2.14 Get Classroom List

6.3.2.15 Get Students In Classroom

6.3.2.16 Get Teachers In Classroom

6.3.2.17 Get Student Record

6.3.2.18 Get Student Record List

6.3.2.19 Create Request To Update Student Record

6.3.2.20 Get Pending Record Requests

6.3.2.21 Approve Pending Record Request

6.3.2.22 Upload Record To Chain Node

6.3.2.23 Create Statistic Key

6.3.2.24 Get Statistic Key List

6.3.2.25 Delete Statistic Key

6.3.2.26 Get Statistic Data

6.3.2.27 Create Student Key

6.3.2.28 Get Student Key List

6.3.2.29 Delete Student Key

6.3.2.30 Get Student Data From Key

6.3.2.31 Upload Legacy Student Record

6.4 Data & Database Design

6.4.1 Database Design

Figure 6.4: Database Design of the Request Server

6.4.1.1 Account

Field Name Type Size Unique Not Null Flag Notes
ID bigint x x PK
USERNAME character varying 255 x x
HASHEDPASSWORD character varying 255 x
SALT character varying 255 x
ROLE character varying 255 x
CREATEDAT timestamp x

6.4.1.2 Profile

Field Name Type Size Unique Not Null Flag Notes
ACCOUNT_ID bigint x x PK, FK
ADDRESS character varying 255 x
AVATAR character varying 255 x
BIRTHDATE timestamp x
EMAIL character varying 255 x
FIRSTNAME character varying 255 x
LASTNAME character varying 255 x
MALE boolean x
PHONE character varying 255 x
UPDATED boolean x Used internally by student updater

6.4.1.3 Student

Field Name Type Size Unique Not Null Flag Notes
ACCOUNT_ID bigint x x PK, FK
ETHNIC character varying 255 x
FATHERJOB character varying 255 x
FATHERNAME character varying 255 x
GUARDIANJOB character varying 255 x
GUARDIANNAME character varying 255 x
HOMETOWN character varying 255 x
MOTHERJOB character varying 255 x
MOTHERNAME character varying 255 x

6.4.1.4 Classroom

Field Name Type Size Unique Not Null Flag Notes
ID bigint x x PK
NAME character varying 255 x
GRADE character varying 255 x
HOMEROOMTEACHER_ID bigint x FK
START_YEAR integer x

6.4.1.5 Class Student

Field Name Type Size Unique Not Null Flag Notes
ID bigint x x PK
CLASSROOM_ID bigint x FK
STUDENT_ID bigint x FK

6.4.1.6 Class Teacher

Field Name Type Size Unique Not Null Flag Notes
ID bigint x x PK
CLASSROOM_ID bigint x FK
TEACHER_ID bigint x FK
SUBJECTID bigint x Defined in the system’s config

6.4.1.7 Record

Field Name Type Size Unique Not Null Flag Notes
ID bigint x x PK
CLASSROOM_ID bigint x FK
STUDENT_ACCOUNT_ID bigint x FK

6.4.1.8 Record Entry

Field Name Type Size Unique Not Null Flag Notes
ID bigint x x PK
RECORD_ID bigint x FK
REQUESTER_ID bigint FK
TEACHER_ID bigint FK
APPROVER_ID bigint FK
APPROVALDATE timestamp x
REQUESTDATE timestamp x
FIRSTHALFSCORE double precision x
SECONDHALFSCORE double precision x
FINALSCORE double precision x
SUBJECTID bigint x Defined in the system’s config
UPDATECOMPLETE boolean x Used internally by student updater

6.4.1.9 Pending Record Entry

Field Name Type Size Unique Not Null Flag Notes
ID bigint x x PK
RECORD_ID bigint x FK
REQUESTER_ID bigint x FK
TEACHER_ID bigint x FK
REQUESTDATE timestamp x
FIRSTHALFSCORE double precision x
SECONDHALFSCORE double precision x
FINALSCORE double precision x
SUBJECTID bigint x Defined in the system’s config

6.4.1.10 Updater Key

Field Name Type Size Unique Not Null Flag Notes
ID character varying 255 x x PK
STUDENT_ACCOUNT_ID bigint x FK

6.4.1.11 Statistic Key

Field Name Type Size Unique Not Null Flag Notes
ID character varying 255 x x PK
GRADE integer x
START_YEAR integer x

6.4.2 Data File Design

File Name Type Notes
db Folder The folder of The H2 Database files
updater Folder Contains the data files of the local student updater